home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / labyte.exe / LABYTE.DOC < prev    next >
Text File  |  1992-05-08  |  20KB  |  482 lines
  1.                              Memory Manager
  2.                               Version S1.1
  3.  
  4.      One of the most difficult parts of programming in C is handling
  5. memory and its pointers.  At least, that is what I found.  To help me
  6. reduce these problems, I  wrote LAByte.
  7.  
  8.      The functions provided are:
  9.      1.   Handling the allocation of memory blocks, freeing the blocks,
  10.           checking for memory corruption.
  11.      2.   Provide a method of tracing the entrance into each function.
  12.  
  13.      NOTE: There are two separate traces maintained by the module.  The
  14.            first is for the memory functions and the second is for
  15.            function tracing.
  16.  
  17. Memory Processor Functions
  18.   All calls are "traced".  If an error occurs the trace table is written
  19.   to a file named LATrace.LAC.  Each of the function calls use the file
  20.   name and line number.  You may supply your own file name as a
  21.   character pointer or use the __FILE__ symbol, likewise, you may use
  22.   __LINE__ symbol for the line number.  More on the trace later.
  23.  
  24.  
  25.   Allocation of Memory
  26.  
  27.      Memory is allocated from the far heap.  A far character pointer is
  28.      returned pointing to the first usable byte of the block.  The block
  29.      is initialized to NULLs.
  30.  
  31.   prototype:
  32.      char far *mem_getmain(char *File, int Line, char Fun1, char Fun2, int Size);
  33.  
  34.      char *File = A name that will point you to the module doing the
  35.                   getmain.  You may use the __FILE__ symbol.
  36.  
  37.      int Line =   A number representing the place in the module where the
  38.                   getmain was called.  You may use the __LINE__ symbol.
  39.  
  40.      char Fun1 =  These characters can be set to anything that will help
  41.      char Fun2    point you in the right direction.  I use the selection
  42.                   characters from the main menu and its pull down menu.
  43.  
  44.      int Size =   The size of the memory block to be allocated.
  45.      
  46.   example:
  47.  
  48.      int Samp_Fun()
  49.      {
  50.       char far *Cnfg;
  51.  
  52.        Cnfg = mem_getmain(__FILE__, __LINE__, 'M', 'C', sizeof(CONFIG_DATA));
  53.  
  54.      }
  55.  
  56.   Freeing A Memory Block
  57.      When called, freemain will verify the integrity of the block
  58.      passed, abending if it is not valid or freeing the block and
  59.      returning to the calling return.  This function can only be
  60.      used to free memory blocks allocated by the getmain function
  61.      because of the trace chain and block integrity header and
  62.      trailer.
  63.  
  64.   prototype:
  65.      int mem_freemain(char *File, int Line, char far *Pointer);
  66.  
  67.      char *File = A name that will point you to the module doing the
  68.                   getmain.  You may use the __FILE__ symbol.
  69.  
  70.      int Line =   A number representing the place in the module where the
  71.                   getmain was called.  You may use the __LINE__ symbol.
  72.  
  73.      char far *Pointer = The pointer returned from the call to getmain.
  74.      
  75.   example:
  76.  
  77.      int Samp_Fun()
  78.      {
  79.       char far *Cnfg;
  80.  
  81.        mem_freemain(__FILE__, __LINE__, Cnfg);
  82.  
  83.      }
  84.  
  85.  
  86.   Freeing Memory Blocks By A Function
  87.      When called, cleanup will verify the integrity of all blocks
  88.      on the chain where the passed function matches the char passed in
  89.      Fun1 of the getmain, abending if an invalid is encountered or
  90.      freeing the block and returning to the calling return.  The reason
  91.      for using cleanup is to eliminate the build up of unreleased memory
  92.      as a function ends or as a quick and easy way to release all memory
  93.      that was allocated to accomplish the function.
  94.  
  95.   prototype:
  96.      int mem_cleanup(char *File, int Line, char Fun);
  97.  
  98.      char *File = A name that will point you to the module doing the
  99.                   getmain.  You may use the __FILE__ symbol.
  100.  
  101.      int Line =   A number representing the place in the module where the
  102.                   getmain was called.  You may use the __LINE__ symbol.
  103.  
  104.      char Fun =   The character passed in Fun1 of the getmain for the
  105.                   blocks to be released.
  106.      
  107.   example:
  108.  
  109.      int Samp_Fun()
  110.      {
  111.  
  112.        mem_cleanup(__FILE__, __LINE__, 'M');
  113.  
  114.      }
  115.  
  116.  
  117.   Freeing All Memory Blocks
  118.      When called, freeall will verify the integrity of all blocks
  119.      on the chain, abending if invalid or freeing the blocks and
  120.      returning to the calling return.
  121.  
  122.   prototype:
  123.      int mem_freeall(char *File, int Line);
  124.  
  125.      char *File = A name that will point you to the module doing the
  126.                   getmain.  You may use the __FILE__ symbol.
  127.  
  128.      int Line =   A number representing the place in the module where the
  129.                   getmain was called.  You may use the __LINE__ symbol.
  130.      
  131.   example:
  132.  
  133.      int Samp_Fun()
  134.      {
  135.  
  136.        mem_freeall(__FILE__, __LINE__);
  137.  
  138.      }
  139.  
  140.  
  141.   Memory Trace Entry
  142.  
  143.      Internal table
  144.           Memory trace entries are allocated from the near heap as
  145.           memory is allocated and added to the chain.  The first trace
  146.           entry address is saved in the anchor in LAByte.C named
  147.           MemAnchor.
  148.  
  149.           typedef struct {
  150.               int  MemOK;        /* Normally NULL but set to a value
  151.                                     if an error is detected.  see
  152.                                     Error Codes below                */
  153.               char MemMod[15];   /* File Name from getmain           */
  154.               int  MemLine;      /* Line Number from getmain         */
  155.               char MemFun;       /* Fun1 from getmain                */
  156.               char MemUse;       /* Fun2 from getmain                */
  157.               int  MemLen;       /* Length from getmain              */
  158.               void far *MemAddr; /* Address of the memory block      */
  159.               void *MemPrev;     /* Address of the previous memory trace
  160.                                     entry or the memory anchor in the
  161.                                     header                           */
  162.               void *MemNext;     /* Address of the next memory trace
  163.                                     entry or null if this is the last
  164.                                     entry on the chain               */
  165.           } MEMTBL;
  166.  
  167.      LATrace.Lac File Entry (see Cancelling The Program below)
  168.  
  169. M---5D8D:0004---0---main.c---25---M---C---365---5D75:0008---6C60:0004---0000:0000
  170. ^-A     ^-B     ^-C   ^-D    ^-E  ^-F ^-G  ^-H    ^-I          ^-J         ^-K
  171.           A)  Indicator showing this as a memory trace entry
  172.           B)  Address of this trace entry
  173.           C)  Error Code, see Error Codes below
  174.           D)  File Name
  175.           E)  Line Number
  176.           F)  Fun1
  177.           G)  Fun2
  178.           H)  Length of the memory block
  179.           I)  Address of the memory block
  180.           J)  Address of previous memory trace entry
  181.           K)  Address of next memory trace entry
  182.  
  183.      Error codes
  184.           mem_freemain function
  185.             1 - There is no memory on the trace chain
  186.             2 - Can't find find the memory block on the chain
  187.             3 - The backward chain has been corrupted
  188.             4 - The forward chain has been corrupted
  189.             5 - The header of the memory block has been corrupted
  190.             6 - The trailer of the memory block has been corrupted
  191.           mem_cleanup function
  192.            11 - The backward chain has been corrupted
  193.            12 - The header of a memory block has been corrupted
  194.            13 - The trailer of a memory block has been corrupted
  195.           mem_freeall function
  196.            21 - The backward chain has been corrupted
  197.            22 - The header of a memory block has been corrupted
  198.            23 - The trailer of a memory block has been corrupted
  199.           If the trailer of a memory block has been corrupted,
  200.           error codes 6, 13 and 23, probably the definition of the area
  201.           is larger than the memory block allocated.
  202.           If the header is corrupted, error codes 5, 12 and 22,
  203.           either the pointer has been changed, an array was
  204.           improperly indexed or the previous area was overrun.
  205.           For all other error codes, the memory trace chain has
  206.           been corrupted